home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / umich / diskutil / dklog.arc / DKLOG.MAN < prev   
Encoding:
Text File  |  1987-04-22  |  8.2 KB  |  212 lines
  1.   Disk Logging Desk Accessory 
  2.   ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  3.   Log all disk i/o and display as required.
  4.  
  5.   copyright Keith  Bedford  August 1989, may be used and distributed freely.
  6.  
  7.  
  8.   To Install: Copy to bootdisk as dsklog.acc and reboot (in any resolution).
  9.               The RWABS vector will revectored to the program and all 
  10.               subsequent  i/o routed through it.  
  11.               Details of each i/o will be logged, including the time between
  12.               actually initiating the i/o and a response being received.
  13.               When the memory buffer is full (120 entries as released) logging
  14.               wraps around to the start of the buffer.
  15.  
  16.   To display log: Invoke as any other Desk Accessory (from leftmost option of
  17.                   Gem menu bar), note that any Gem program should allow access.
  18.                   A window is opened and the last (newest) page of log data 
  19.                   displayed as below:
  20.  
  21.                   Op Dk Sctr/count   Buffer   Rslt/Secs
  22.  
  23.                   where Op is the operation (Read or Write) performed on disk
  24.                   Dk, which started at sector Sctr for count sectors to or 
  25.                   from buffer. The return code was Rslt and the operation took
  26.                   Secs to complete.
  27.  
  28.                   Page through the log entries using the elevator or scroll by
  29.                   using the scroll arrows.
  30.  
  31.                   The window cannot be fulled, resized or moved.
  32.  
  33.                   Other windows can be topped and manipulated and the log
  34.                   window returned to.  Disk i/o will continue to be logged
  35.                   whilst the log window is open, however the display will start
  36.                   to get confused.
  37.  
  38.                   Close the window to exit.
  39.  
  40.   Applications:   As cache programs work this way it provides a good way to 
  41.                   decide which cache mechanism would be best to use, run your 
  42.                   favourite editor / compiler / word processor / spreadsheet 
  43.                   or whatever and then see how the i/o's were performed.  
  44.                   Some programs read lots of single pages even when several 
  45.                   could be read at once, these will benefit from a read-ahead 
  46.                   cache, ie one that reads a complete track (or 10 sectors) in 
  47.                   the hope that the sectors following the one requested will be 
  48.                   asked for next.
  49.                   Other programs always read as much data as possible, these
  50.                   will benefit more from a cache that keeps the most frequently
  51.                   accessed sectors in memory.
  52.  
  53.                   Different disk formats can be tried to see which gives the
  54.                   best results (ie fastest transfers) and you can see where 
  55.                   delays occur.
  56.  
  57.                   The last disk operation a failing program performs can be
  58.                   determined, typically PD programs expect resource or data 
  59.                   files to be somewhere obscure that was blindingly obvious to
  60.                   the programmer but not to you!  And the error messages are
  61.                   usually gibberish (Err #53) or misleading. 
  62.                   If you can navigate around a disk you can now see the last
  63.                   directory that was read.
  64.  
  65.                   Two example uses are documented in ramdisk.tst and 
  66.                   fformat.tst.
  67.  
  68. Bugs:  Sometimes the DA refuses to run from the Menu bar, I can't discover 
  69.        why but believe its a Gem problem (no programmer believes his
  70.        programs are faulty!).
  71.  
  72.        Although the program works in any resolution, changing resolution
  73.        whilst it is installed will crash the ST and require a RESET.
  74.        I dont know why this is, I believe I've seen similar problems with
  75.        other DA's, does any bright spark know what the problem is?
  76.  
  77. Possible enhancements:
  78.        The missing Gem window functions could be added, I didn't think they
  79.        were required for this application but someone might.
  80.  
  81.        The buffer is cleared by RESETting, it could be kept in high memory 
  82.        with a checksum attached to it, on booting the DA should verify the
  83.        checksum and if ok keep the log data already in the buffer.
  84.        The size of the buffer could also be changed dynamically.
  85.  
  86.        The log could be output to a disk file or printer.
  87.  
  88.        I have released the source file to allow anyone to make any changes
  89.        they require, and also use it as inspiration for writing their own
  90.        Desk Accessories and Gem programs.
  91.  
  92. Programming notes:
  93.  
  94. Desk Accessory: As can be seen from the source file - dont release unrequired
  95.        memory, do connect to AES, register as a Desk Accessory supplying your 
  96.        menu text and drop into Event-multi to wait to be called.  Messages 
  97.        will arrive that aren't for you - check that the message is an accessory
  98.        open and carries your application-id before acting upon it.  Never exit
  99.        from a Desk Accessory, just go back to Event-multi.
  100.  
  101.        The hardest thing about Desk Accessories is testing and debugging them,
  102.        its best to do as much testing as possible as a program which can be
  103.        executed directly or under a debugger. The source file contains 
  104.        comments on changes to be made to run DKLOG as a program for example.
  105.  
  106. Gem Windows: Release unrequired memory, connect to Aes, open your window,
  107.        lock Gem whilst you are updating it, release Gem and drop into
  108.        Event-multi to wait for user instructions. When you get a message
  109.        check its for you then carry it out and back to Event-multi unless
  110.        the message was close-window, in which case exit the program
  111.        (assuming a simple single window program).
  112.  
  113.        Many of the routines in the source file can be re-used, as follows:
  114.  
  115.   Open window
  116.   ~~~~~~~~~~~
  117. opnwndw:
  118.   Parameters on stack:
  119.     +18 - screen column for first window column
  120.     +16 - screen row for window title
  121.     +14 - number of columns in window
  122.     +12 - number of rows in window
  123.     +8 - text for title
  124.     +4 - text for information line
  125.   Processing:
  126.     Find graphics handle, open a virtual workstation, saving handle.
  127.     Calculate screen resolution from number of colours, convert character 
  128.     coordinates to pixels. Calculate window position and size and create.
  129.     Set title and info line and open window.
  130.     Set writing mode (replace) and clipping rectangle.
  131.     Set colours and clear window.
  132.     Define writing area within window.
  133.     Set mouse shape (not needed for Desk accessory).
  134.  
  135.     This window will automatically be used by the following routines.
  136.  
  137.   Lock Gem
  138.   ~~~~~~~~
  139. start_update:
  140.   No parameters
  141.   Processing:
  142.     Remove cursor from screen
  143.     Lock Gem
  144.  
  145.   Clear window
  146.   ~~~~~~~~~~~~
  147. clrwndw:
  148.   No parameters
  149.   Processing:
  150.     Fill window with white space
  151.  
  152.   Write to window
  153.   ~~~~~~~~~~~~~~~
  154. wrwindow:
  155.   Parameters passed on stack:
  156.      +4 - horizontal co-ord 
  157.      +6 - vertical co-ord
  158.      +8 - text address
  159.  
  160.   Processing:
  161.      convert co-ordinates to pixels
  162.      copy text to buffer until first non-printable character
  163.      display buffer
  164.  
  165.   Unlock Gem
  166.   ~~~~~~~~~~
  167. end_update:
  168.   No parameters
  169.   Processing:
  170.     Return cursor to screen
  171.     Unlock Gem
  172.  
  173.   Set window elevator size
  174.   ~~~~~~~~~~~~~~~~~~~~~~~~
  175. windsize:
  176.   Parameter on stack:
  177.     +4 - size of window as a function of buffer size
  178.   Processing:
  179.     Call Aes to set size of elevator
  180.  
  181.   Set window elevator position
  182.   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  183. windpos:
  184.   Parameter on stack:
  185.     +4 - position of window within buffer
  186.   Processing:
  187.     Call Aes to set position of elevator
  188.  
  189.   Close and delete window
  190.   ~~~~~~~~~~~~~~~~~~~~~~~
  191. closewindow:
  192.   No parameters
  193.   Processing:
  194.      Close virtual workstation
  195.      Close window
  196.      Delete window
  197.  
  198.  
  199.  Call AES
  200.  ~~~~~~~~
  201.   Parameter: D1 ->parameter list, on return d0.w = intout
  202.  
  203.  Call VDI
  204.  ~~~~~~~~
  205.   Parameter: D1 ->parameter block
  206.  
  207.  
  208.  Note the use of pre-defined parameter blocks for most Aes and Vdi calls,
  209.  it is usually most efficient to let the assembler do the work for you,
  210.  both in speed and size of generated code.  Leave Basic programmers to
  211.  set up enormous parameter blocks at run time.
  212.